;+
; NAME:
;       pLEGEND     
; PURPOSE:
;	Create an annotation legend for a plot.
; EXPLANATION:
;	This procedure makes a legend for a plot.  The legend can contain
;	a mixture of symbols, linestyles, Hershey characters (vectorfont),
;	and filled polygons (usersym).  A test procedure, legendtest.pro,
;	shows legend's capabilities.  Placement of the legend is controlled
;	with keywords like /right, /top, and /center or by using a position
;	keyword for exact placement (position=[x,y]) or via mouse (/position).
; CALLING SEQUENCE:
;      	pLEGEND [,items][,keyword options]
; EXAMPLES:
;	The call:
;		plegend,['Plus sign','Asterisk','Period'],psym=[1,2,3]
;	  produces:
;		-----------------
;		|		|
;		|  + Plus sign	|
;		|  * Asterisk	|
;		|  . Period	|
;		|		|
;		-----------------
;	  Each symbol is drawn with a plots command, so they look OK.
;	  Other examples are given in optional output keywords.
;
;	lines = indgen(6)			; for line styles
;	items = 'linestyle '+strtrim(lines,2)	; annotations
;	plegend,items,linestyle=lines		; vertical legend---upper left
;	items = ['Plus sign','Asterisk','Period']
;	sym = [1,2,3]
;	plegend,items,psym=sym			; ditto except using symbols
;	plegend,items,psym=sym,/horizontal	; horizontal format
;	plegend,items,psym=sym,box=0		; sans border
;	plegend,items,psym=sym,delimiter='='	; embed '=' betw psym & text
;	plegend,items,psym=sym,margin=2		; 2-character margin
;	plegend,items,psym=sym,position=[x,y]	; upper left in data coords
;	plegend,items,psym=sym,pos=[x,y],/norm	; upper left in normal coords
;	plegend,items,psym=sym,pos=[x,y],/device	; upper left in device coords
;	plegend,items,psym=sym,/position		; interactive position
;	plegend,items,psym=sym,/right		; at upper right
;	plegend,items,psym=sym,/bottom		; at lower left
;	plegend,items,psym=sym,/center		; approximately near center
;	plegend,items,psym=sym,number=2		; plot two symbols, not one
;	plegend,items,/fill,psym=[8,8,8],colors=[10,20,30]; 3 filled squares
; INPUTS:
;	items = text for the items in the legend, a string array.
;		For example, items = ['diamond','asterisk','square'].
;		You can omit items if you don't want any text labels.
; OPTIONAL INPUT KEYWORDS:
;
;	linestyle = array of linestyle numbers  If linestyle(i) < 0, then omit
;		ith symbol or line to allow a multi-line entry.
;	psym = array of plot symbol numbers.  If psym(i) is negative, then a
;		line connects pts for ith item.  If psym(i) = 8, then the
;		procedure usersym is called with vertices define in the 
;		keyword usersym.   If psym(i) = 88, then use the previously 
;		defined user symbol
;	vectorfont = vector-drawn characters for the sym/line column, e.g.,
;		['!9B!3','!9C!3','!9D!3'] produces an open square, a checkmark,
;		and a partial derivative, which might have accompanying items
;		['BOX','CHECK','PARTIAL DERIVATIVE'].  
;		There is no check that !p.font is set properly, e.g., -1 for
;		X and 0 for PostScript.  This can produce an error, e.g., use
;		!20 with PostScript and !p.font=0, but allows use of Hershey
;		*AND* PostScript fonts together.
;	N. B.: Choose any of linestyle, psym, and/or vectorfont.  If none is
;		present, only the text is output.  If more than one
;		is present, all need the same number of elements, and normal 
;		plot behaviour occurs.
;		By default, if psym is positive, you get one point so there is
;		no connecting line.  If vectorfont(i) = '',
;		then plots is called to make a symbol or a line, but if
;		vectorfont(i) is a non-null string, then xyouts is called.
;	/help = flag to print header
;	/horizontal = flag to make the legend horizontal
;	/vertical = flag to make the legend vertical (D=vertical)
;	box = flag to include/omit box around the legend (D=include)
;	clear = flag to clear the box area before drawing the legend 
;	delimiter = embedded character(s) between symbol and text (D=none)
;	colors = array of colors for plot symbols/lines (D=!color)
;	textcolors = array of colors for text (D=!color)
;	margin = margin around text measured in characters and lines
;	spacing = line spacing (D=bit more than character height)
;	pspacing = psym spacing (D=3 characters)
;	charsize = just like !p.charsize for plot labels
;	thick = array of line thickness numbers, if used, then linestyle 
;		must also be specified   
;	position = data coordinates of the /top (D) /left (D) of the legend
;	normal = use normal coordinates for position, not data
;	device = use device coordinates for position, not data
;	number = number of plot symbols to plot or length of line (D=1)
;	usersym = 2-D array of vertices, cf. usersym in IDL manual. (D=square)
;	/fill = flag to fill the usersym
;	/left = flag to place legend snug against left side of plot window (D)
;	/right = flag to place legend snug against right side of plot window
;		If /right,pos=[x,y], then x is position of RHS and text
;		runs right-to-left.
;	/top = flag to place legend snug against top of plot window (D)
;	/bottom = flag to place legend snug against bottom of plot window
;		/top,pos=[x,y] and /bottom,pos=[x,y] produce same positions.
;
;	If LINESTYLE, PSYM, VECTORFONT, THICK, COLORS, or TEXTCOLORS are 
;	supplied as scalars, then the scalar value is set for every line or 
;	symbol in the legend.
; Outputs:
;	legend to current plot device
; OPTIONAL OUTPUT KEYWORDS: 
;	corners = 4-element array, like !p.position, of the normalized
;	  coords for the box (even if box=0): [llx,lly,urx,ury].
;	  Useful for multi-column or multi-line legends, for example,
;	  to make a 2-column legend, you might do the following:
;	    c1_items = ['diamond','asterisk','square']
;	    c1_psym = [4,2,6]
;	    c2_items = ['solid','dashed','dotted']
;	    c2_line = [0,2,1]
;	    plegend,c1_items,psym=c1_psym,corners=c1,box=0
;	    legend,c2_items,line=c2_line,corners=c2,box=0,pos=[c1(2),c1(3)]
;	    c = [c1(0)<c2(0),c1(1)<c2(1),c1(2)>c2(2),c1(3)>c2(3)]
;	    plots,[c(0),c(0),c(2),c(2),c(0)],[c(1),c(3),c(3),c(1),c(1)],/norm
;	  Useful also to place the legend.  Here's an automatic way to place
;	  the legend in the lower right corner.  The difficulty is that the
;	  legend's width is unknown until it is plotted.  In this example,
;	  the legend is plotted twice: the first time in the upper left, the
;	  second time in the lower right.
;	    plegend,['1','22','333','4444'],linestyle=indgen(4),corners=corners
;			; BOGUS LEGEND---FIRST TIME TO REPORT CORNERS
;	    xydims = [corners(2)-corners(0),corners(3)-corners(1)]
;			; SAVE WIDTH AND HEIGHT
;	    chdim=[!d.x_ch_size/float(!d.x_size),!d.y_ch_size/float(!d.y_size)]
;			; DIMENSIONS OF ONE CHARACTER IN NORMALIZED COORDS
;	    pos = [!x.window(1)-chdim(0)-xydims(0) $
;			,!y.window(0)+chdim(1)+xydims(1)]
;			; CALCULATE POSITION FOR LOWER RIGHT
;	    plot,findgen(10)	; SIMPLE PLOT; YOU DO WHATEVER YOU WANT HERE.
;	    plegend,['1','22','333','4444'],linestyle=indgen(4),pos=pos
;			; REDO THE LEGEND IN LOWER RIGHT CORNER
;	  You can modify the pos calculation to place the legend where you
;	  want.  For example to place it in the upper right:
;	    pos = [!x.window(1)-chdim(0)-xydims(0),!y.window(1)-xydims(1)]
; Common blocks:
;	none
; Procedure:
;	If keyword help is set, call doc_library to print header.
;	See notes in the code.  Much of the code deals with placement of the
;	legend.  The main problem with placement is not being
;	able to sense the length of a string before it is output.  Some crude
;	approximations are used for centering.
; Restrictions:
;	Here are some things that aren't implemented.
;	- An orientation keyword would allow lines at angles in the legend.
;	- An array of usersyms would be nice---simple change.
;	- An order option to interchange symbols and text might be nice.
;	- Somebody might like double boxes, e.g., with box = 2.
;	- Another feature might be a continuous bar with ticks and text.
;	- There are no guards to avoid writing outside the plot area.
;	- There is no provision for multi-line text, e.g., '1st line!c2nd line'
;	  Sensing !c would be easy, but !c isn't implemented for PostScript.
;	  A better way might be to simply output the 2nd line as another item
;	  but without any accompanying symbol or linestyle.  A flag to omit
;	  the symbol and linestyle is linestyle(i) = -1.
;	- There is no ability to make a title line containing any of titles
;	  for the legend, for the symbols, or for the text.
; Side Effects:
; Modification history:
;	write, 24-25 Aug 92, F K Knight (knight@ll.mit.edu)
;	allow omission of items or omission of both psym and linestyle, add 
;	  corners keyword to facilitate multi-column legends, improve place-
;	  ment of symbols and text, add guards for unequal size, 26 Aug 92, FKK
;	add linestyle(i)=-1 to suppress a single symbol/line, 27 Aug 92, FKK
;	add keyword vectorfont to allow characters in the sym/line column,
;	  28 Aug 92, FKK
;	add /top, /bottom, /left, /right keywords for automatic placement at
;	  the four corners of the plot window.  The /right keyword forces
;	  right-to-left printing of menu. 18 Jun 93, FKK
;	change default position to data coords and add normal, data, and
;	  device keywords, 17 Jan 94, FKK
;	add /center keyword for positioning, but it is not precise because
;	  text string lengths cannot be known in advance, 17 Jan 94, FKK
;	add interactive positioning with /position keyword, 17 Jan 94, FKK
;	allow a legend with just text, no plotting symbols.  This helps in
;	  simply describing a plot or writing assumptions done, 4 Feb 94, FKK
;	added thick, symsize, and clear keyword Feb 96, W. Landsman HSTX 
;		David Seed, HR Wallingford, d.seed@hrwallingford.co.uk
;	allow scalar specification of keywords, Mar 96, W. Landsman HSTX
;	Converted to IDL V5.0   W. Landsman   September 1997
;
;	Erin Sheldon.  
;		renamed plegend
;		Added bcolor keyword for box color
;		added ability to use c2i color name to color index converter
;		default is no box
;       
;-
pro plegend,help=help,items,linestyle=linestyle,psym=psym,$
           vectorfont=vectorfont $
           ,horizontal=horizontal,vertical=vertical,box=box,margin=margin $
           ,delimiter=delimiter,spacing=spacing,charsize=charsize,$
           pspacing=pspacing $
           ,position=position,number=number,colors=colors,$
           textcolors=textcolors, $
           bcolor=bcolor $
           ,fill=fill,usersym=usersym,corners=corners $
           ,left=left,right=right,top=top,bottom=bottom,center=center $
           ,data=data,normal=normal,device=device $
           ,symsize=symsize,thick=thick,clear=clear
;
;	=====>> HELP
;
on_error,2
if keyword_set(help) then begin & doc_library,'plegend' & return & endif
;
;	=====>> SET DEFAULTS FOR SYMBOLS, LINESTYLES, AND ITEMS.
;
ni = n_elements(items)
np = n_elements(psym)
nl = n_elements(linestyle)
nth = n_elements(thick)
nv = n_elements(vectorfont)
nlpv = max([np,nl,nv])
n = max([ni,np,nl,nv])					; NUMBER OF ENTRIES
strn = strtrim(n,2)	
IF n_elements(bcolor) EQ 0 THEN bcolor=!p.background ; FOR ERROR MESSAGES
if n eq 0 then message,'No inputs!  For help, type legend,/help.'
if ni eq 0 then begin
  items = replicate('',n)				; DEFAULT BLANK ARRAY
endif else begin
  szt = size(items)
  if (szt[szt[0]+1] ne 7) then message,'First parameter must be a string array.  For help, type legend,/help.'
  if ni ne n then message,'Must have number of items equal to '+strn
endelse
symline = (np ne 0) or (nl ne 0)			; FLAG TO PLOT SYM/LINE
 if (np ne 0) and (np ne n) and (np NE 1) then message, $
        'Must have 0, 1 or '+strn+' elements in PSYM array.'
 if (nl ne 0) and (nl ne n) and (nl NE 1) then message, $
         'Must have 0, 1 or '+strn+' elements in LINESTYLE array.'
 if (nth ne 0) and (nth ne n) and (nth NE 1) then message, $
         'Must have 0, 1 or '+strn+' elements in THICK array.'

 if nl EQ 0 then linestyle = intarr(n) else $           D=SOLID
	 if nl EQ 1 then linestyle = intarr(n)  + linestyle 
 if nth EQ 0 then thick=replicate(!p.thick,n) else  $
	 if nth EQ 1 then thick = replicate(fix(thick),n) 
 if np EQ 0 then psym = intarr(n) else $		; D=SOLID
	 if np EQ 1 then psym = intarr(n) + psym
 if nv EQ 0 then vectorfont = replicate('',n) else $
	if nv EQ 1 then vectorfont = replicate(vectorfont,n)	
;
;	=====>> CHOOSE VERTICAL OR HORIZONTAL ORIENTATION.
;
if n_elements(horizontal) eq 0 then begin 		; D=VERTICAL
  if n_elements(vertical) eq 0 then vertical = 1
endif else begin
  if n_elements(vertical) eq 0 then vertical = not horizontal
endelse
;
;	=====>> SET DEFAULTS FOR OTHER OPTIONS.
;
if n_elements(box) eq 0 then box = 0
if n_elements(clear) eq 0 then clear = 0

if n_elements(margin) eq 0 then margin = 0.5
if n_elements(delimiter) eq 0 then delimiter = ''
if n_elements(charsize) eq 0 then charsize = !p.charsize
if charsize eq 0 then charsize = 1
if (n_elements (symsize) eq 0) then symsize= charsize + intarr(n)
if n_elements(number) eq 0 then number = 1

if n_elements(colors) eq 0 then begin
	carr = !P.color + lonarr(n) 
endif else begin
	if size(colors,/tname) eq 'STRING' then begin
		; requires c2i function which may not exist
		comm = 'carr = c2i(colors)'
		if not execute(comm) then begin
			carr = !p.color + lonarr(n)
		endif
	endif else begin
		carr = colors + lonarr(n)
	endelse
endelse


if n_elements(textcolors) eq 0 then textcolors = !P.color + intarr(n) else $
	if N_elements(textcolors) EQ 1 then textcolors = textcolors + intarr(n)
fill = keyword_set(fill)
if n_elements(usersym) eq 0 then usersym = 2*[[0,0],[0,1],[1,1],[1,0]]-1
;
;	=====>> INITIALIZE SPACING
;
if n_elements(spacing) eq 0 then spacing = 1.2
if n_elements(pspacing) eq 0 then pspacing = 3
xspacing = !d.x_ch_size/float(!d.x_size) * (spacing > charsize)
yspacing = !d.y_ch_size/float(!d.y_size) * (spacing > charsize)
ltor = 1					; flag for left-to-right
if n_elements(left) eq 1 then ltor = left eq 1
if n_elements(right) eq 1 then ltor = right ne 1
ttob = 1					; flag for top-to-bottom
if n_elements(top) eq 1 then ttob = top eq 1
if n_elements(bottom) eq 1 then ttob = bottom ne 1
xalign = ltor ne 1				; x alignment: 1 or 0
yalign = -0.5*ttob + 1				; y alignment: 0.5 or 1
xsign = 2*ltor - 1				; xspacing direction: 1 or -1
ysign = 2*ttob - 1				; yspacing direction: 1 or -1
if not ttob then yspacing = -yspacing
if not ltor then xspacing = -xspacing
;
;	=====>> INITIALIZE POSITIONS: FIRST CALCULATE X OFFSET FOR TEXT
;
xt = 0
if nlpv gt 0 then begin				; SKIP IF TEXT ITEMS ONLY.
if vertical then begin				; CALC OFFSET FOR TEXT START
  for i = 0,n-1 do begin
    if (psym[i] eq 0) and (vectorfont[i] eq '') then num = (number + 1) > 3 else num = number
    if psym[i] lt 0 then num = number > 2	; TO SHOW CONNECTING LINE
    if psym[i] eq 0 then expand = 1 else expand = 2
    thisxt = (expand*pspacing*(num-1)*xspacing)
    if ltor then xt = thisxt > xt else xt = thisxt < xt
    endfor
endif	; NOW xt IS AN X OFFSET TO ALIGN ALL TEXT ENTRIES.
endif
;
;	=====>> INITIALIZE POSITIONS: SECOND LOCATE BORDER
;
if !x.window[0] eq !x.window[1] then begin
  plot,/nodata,xstyle=4,ystyle=4,[0],/noerase
endif
;	next line takes care of weirdness with small windows
pos = [min(!x.window),min(!y.window),max(!x.window),max(!y.window)]
case n_elements(position) of
 0: begin
  if ltor then px = pos[0] else px = pos[2]
  if ttob then py = pos[3] else py = pos[1]
  if keyword_set(center) then begin
    if not keyword_set(right) and not keyword_set(left) then $
      px = (pos[0] + pos[2])/2. - xt
    if not keyword_set(top) and not keyword_set(bottom) then $
      py = (pos[1] + pos[3])/2. + n*yspacing
    endif
  position = [px,py] + [xspacing,-yspacing]
  end
 1: begin	; interactive
  message,/inform,'Place mouse at upper left corner and click any mouse button.'
  cursor,x,y,/normal
  position = [x,y]
  end
 2: begin	; convert upper left corner to normal coordinates
  if keyword_set(data) then $
    position = convert_coord(position,/to_norm) $
  else if keyword_set(device) then $
    position = convert_coord(position,/to_norm,/device) $
  else if not keyword_set(normal) then $
    position = convert_coord(position,/to_norm)
  end
 else: message,'Position keyword can have 0, 1, or 2 elements only. Try legend,/help.'
endcase 

yoff = 0.25*yspacing*ysign			; VERT. OFFSET FOR SYM/LINE.

x0 = position[0] + (margin)*xspacing		; INITIAL X & Y POSITIONS
y0 = position[1] - margin*yspacing + yalign*yspacing	; WELL, THIS WORKS!
;
;	=====>> OUTPUT TEXT FOR LEGEND, ITEM BY ITEM.
;	=====>> FOR EACH ITEM, PLACE SYM/LINE, THEN DELIMITER,
;	=====>> THEN TEXT---UPDATING X & Y POSITIONS EACH TIME.
;	=====>> THERE ARE A NUMBER OF EXCEPTIONS DONE WITH IF STATEMENTS.
;
for iclr = 0,clear do begin
    y = y0                      ; STARTING X & Y POSITIONS
    x = x0
    if ltor then xend = 0 else xend = 1 ; SAVED WIDTH FOR DRAWING BOX

    if ttob then ii = [0,n-1,1] else ii = [n-1,0,-1]
    for i = ii[0],ii[1],ii[2] do begin
        if vertical then x = x0 else y = y0 ; RESET EITHER X OR Y
        x = x + xspacing        ; UPDATE X & Y POSITIONS
        y = y - yspacing
        if nlpv eq 0 then goto,TEXT_ONLY ; FLAG FOR TEXT ONLY
        if (psym[i] eq 0) and (vectorfont[i] eq '') then num = (number + 1) > 3 else num = number
        if psym[i] lt 0 then num = number > 2 ; TO SHOW CONNECTING LINE
        if psym[i] eq 0 then expand = 1 else expand = 2
        xp = x + expand*pspacing*indgen(num)*xspacing
        if (psym[i] gt 0) and (num eq 1) and vertical then xp = x + xt/2.
        yp = y + intarr(num)
        if vectorfont[i] eq '' then yp = yp + yoff
        if psym[i] eq 0 then begin
            xp = [min(xp),max(xp)] ; TO EXPOSE LINESTYLES
            yp = [min(yp),max(yp)] ; DITTO
        endif
;        if psym[i] eq 8 then usersym,usersym,fill=fill,color=colors[i]
        ;; extra by djseed .. psym=88 means use the already defined usersymbol
;        if psym[i] eq 88 then psym[i] =8
        if vectorfont[i] ne '' then begin
;    if (num eq 1) and vertical then xp = x + xt/2	; IF 1, CENTERED.
            xyouts,xp,yp,vectorfont[i],width=width,color=carr[i] $
              ,size=charsize,align=xalign,/norm
            xt = xt > width
            xp = xp + width/2.
        endif else BEGIN

            if symline and (linestyle[i] ge 0) then plots,xp,yp,color=carr[i] $
              ,/normal,linestyle=linestyle[i],psym=psym[i],symsize=symsize[i], $
              thick=thick[i]
        endelse

        if vertical then x = x + xt else if ltor then x = max(xp) else x = min(xp)
        if symline then x = x + xspacing
        TEXT_ONLY:
        xyouts,x,y,delimiter,width=width,/norm,color=textcolors[i],size=charsize,align=xalign
        x = x + width*xsign
        if width ne 0 then x = x + 0.5*xspacing
        xyouts,x,y,items[i],width=width,/norm,color=textcolors[i],size=charsize,align=xalign
        x = x + width*xsign
        if not vertical and (i lt (n-1)) then x = x+2*xspacing ; ADD INTER-ITEM SPACE
        xfinal = (x + xspacing*margin)
        if ltor then xend = xfinal > xend else xend = xfinal < xend ; UPDATE END X
    endfor

    if (iclr lt clear ) then begin
;	=====>> CLEAR AREA
        x = position[0]
        y = position[1]
        if vertical then bottom = n else bottom = 1
        ywidth = - (2*margin+bottom-0.5)*yspacing
        corners = [x,y+ywidth,xend,y]
;        polyfill,[x,xend,xend,x,x],y + [0,0,ywidth,ywidth,0],/norm,color=-1
        polyfill,[x,xend,xend,x,x],y + [0,0,ywidth,ywidth,0],/norm,$
          color=bcolor[0]
;	plots,[x,xend,xend,x,x],y + [0,0,ywidth,ywidth,0],thick=2
    endif else begin

;
;	=====>> OUTPUT BORDER
;
        x = position[0]
        y = position[1]
        if vertical then bottom = n else bottom = 1
        ywidth = - (2*margin+bottom-0.5)*yspacing
        corners = [x,y+ywidth,xend,y]
        if box then plots,[x,xend,xend,x,x],y + [0,0,ywidth,ywidth,0],/norm
        return
    endelse
endfor

end

